home *** CD-ROM | disk | FTP | other *** search
/ Info-Mac 4 / Info_Mac IV CD-ROM (Pacific HiTech Inc.)(August 1994).iso / Science / MandelZot 4.0.1 docs Folder / ECI.h next >
Text File  |  1993-05-16  |  17KB  |  459 lines
  1. /*
  2.         Data definitions for the MandelZot external function
  3.         interface.
  4. */
  5.  
  6. #include <Types.h>
  7.  
  8. #define ECIVERSION 0x0100        /* version 1.0 per Apple's numbering style */
  9.  
  10. typedef union Arg                        /* Argument variants */
  11.     {
  12.         void                 *p;                        /* generic pointer */
  13.         Handle                h;                        /* generic handle */
  14.         char                    c;                        /* single character */
  15.         char                    bool;                    /* one-byte boolean */
  16.         short int            si;                        /* 16-bit integer */
  17.         long int            li;                        /* 32-bit integer */
  18.         long int            flags;                /* 32 one-bit flags */
  19.         float                    f;                        /* SANE/IEEE single-precision floating */
  20.         short double  d;                        /* SANE/IEEE double-precision floating */
  21.         double                e;                        /* SANE *or* IEEE extended-precision */
  22.         Rect                    r;                        /* QuickDraw rectangle */
  23.         char                    filler[12];
  24.     } Arg;
  25.  
  26. typedef struct ECD                    /* External Code descriptor */
  27.     {
  28.         Handle                private;            /* handle to module-specific private data, if any */
  29.         int                        resFileRefNum;/* refNum of resource file, if open... or 0 */
  30.         long int            opaque[];            /* remainder of structure is opaque to the ECM */
  31.     } ECD, **ECDHandle;
  32.  
  33. typedef struct ECP                    /* External Code parameter structure */
  34.     {
  35.         long int            functionCode;    /* function code being requested */
  36.         Arg                        arg[16];            /* up to 16 arguments per call */
  37.     } ECP, **ECPHandle;
  38.  
  39. typedef struct ECO                    /* External Code overhead structure */
  40.     {
  41.         ECDHandle            ECD;                                            /* handle to code descriptor structure */
  42.         Handle                viewHandle;                                /* opaque handle to view structure */
  43.         Handle                private;                                    /* handle to view-specific private data, if any */
  44.         pascal long int            (*util)(struct ECO **,
  45.                                                     struct ECP *);        /* pointer to MandelZot "pascal" utility callback */
  46.     } ECO, **ECOHandle;
  47.  
  48. /*
  49.         Data bits describing ECM's requirements
  50. */
  51.  
  52. #define NeedFPU                        0x80000000
  53. #define NeedIEEEformat        0x40000000
  54. #define NeedResources            0x20000000
  55. #define NeedLockSelf            0x10000000
  56. #define NeedLockAll                0x08000000
  57. #define NeedConfigure            0x04000000
  58.  
  59. /*
  60.         Data bits describing ECM's capabilities
  61. */
  62.  
  63. #define DoMarianiSilver        0x80000000
  64. #define DoDistEstimator        0x40000000
  65. #define DoJulias                    0x20000000
  66. #define DoByPoint                    0x10000000
  67. #define DoByBatch                    0x08000000
  68. #define DoBroadband                0x04000000
  69. #define DoSyncOrbits      0x02000000
  70.  
  71. /*
  72.         Data bits describing symmetry
  73. */
  74.  
  75. #define SymmetryHoriz            0x0001
  76. #define SymmetryVert            0x0002
  77. #define SymmetryOrigin        0x0004
  78.  
  79. /*
  80.         Data bits describing math modes supported/used
  81. */
  82.  
  83. #define Math16bit                    0x0001
  84. #define Math32bit                    0x0002
  85. #define MathSANE                    0x0004
  86. #define Math881                        0x0008
  87.  
  88. /*
  89.         Values returned from the CalcTimeSlice call
  90. */
  91.  
  92. #define SliceSuspend            -1
  93. #define SliceOK                        0
  94. #define SliceIdle                    1
  95. #define SliceDone                    2
  96.  
  97. /*
  98.         File and resource types etc.
  99. */
  100.  
  101. #define CustomFileType        'CUST'
  102. #define CustomResType            'CUST'
  103. #define CustomResID                0
  104. #define CustomResRange        1024
  105. #define CustomResRangeEnd    2047
  106.  
  107. /*
  108.         Values and masks for dwell counts.
  109.         
  110.         Dwell values are stored in 16-bit integers.  The rightmost 15 bits
  111.         are the dwell value (in the range 0 through 32765), or "in the M-set"
  112.         (32766) or "unknown at this time" (32767).  The leftmost bit is a flag
  113.         used to indicate that the value in the rightmost 15 bits is approximate
  114.         or inexact, and should be recalculated;  this bit is set when a window is
  115.         resized upwards, or the calculation parameters are changed.
  116.         
  117. */
  118.  
  119. #define MaxLegalDwell    32765
  120. #define InTheSet            32766
  121. #define Unknown                32767
  122. #define RecalcBit            0x8000
  123. #define DwellMask            0x7FFF
  124.  
  125. /*
  126.         Function codes passed in to ECM from the program
  127. */
  128.  
  129. enum ECFunction
  130.     {
  131.         GetGeneralInfo                = 0,
  132.         InitECM                                = 1,
  133.         GetDefaults                        = 2,
  134.         SetupView                            = 3,
  135.         ConfigureView                    = 4,
  136.         SetupCalcs                        = 5,
  137.         CalcsGo                                = 6,
  138.         CalcsStop                            = 7,
  139.         CalcOne                                = 8,
  140.         CalcTimeSlice                    = 9,
  141.         KillView                            = 10,
  142.         KillECM                                = 11,
  143.         GetViewInfo                        = 12,
  144.         InvalInternals                = 13,
  145.         GetViewString                    = 14,
  146.         InitIncrementalState    = 15,
  147.         CalcIncremental       = 16
  148.     };
  149.  
  150. /*
  151.         Parameter definitions for the various callins
  152.         
  153.         "->" represents a value passed into the ECM
  154.         "<-" represents a value filled in by the ECM prior to returning.
  155.  
  156. ---
  157.  
  158.         GetGeneralInfo.  Called during program initialization.  ECM should fill in
  159.         specified values and return, taking no other actions.  [N.B.  This is the
  160.         only callin which can occur before the first InitECM.]
  161.  
  162.         [0].si            ->        Interface version against which program was compiled.
  163.         [0].si            <-        Interface version number against which the ECM was
  164.                                             compiled.  If too old, ECM will not be usable.
  165.         [1].flags        <-        "Needs" flags, or'ed together
  166.         [2].flags        <-        "Does" flags, or'ed together.
  167.         [3].flags        <-        "Math" flags, or'ed together
  168.  
  169. ---        
  170.         
  171.         InitECM.  Called when ECM's code resource is first read in.  ECM should set
  172.         up any desired global-state code, storing handle into the ECD structure.
  173.         
  174.         No data is passed in or out.
  175.  
  176. ---
  177.  
  178.         GetDefaults.  Called during the "New view" dialog, when an ECM is selected from
  179.         the popup menu, or when the julia-set status box changes.
  180.         
  181.         [0].bool        ->        if true, the ECM should return the appropriate default
  182.                                             values for a Julia-set image.  If false, the ECM should
  183.                                             return the appropriate defaults for an M-like image.
  184.         
  185.         [0].d                <-        Minimum real value displayed in window
  186.         [1].d                <-        Maximum real value displayed in window
  187.         [2].d                <-        Minimum imaginary value displayed in window
  188.         [3].d                <-        Maximum imaginary value displayed in window
  189.         [4].si            <-        Dwell limit [0..32765]
  190.         [5].d                <-        Escape radius
  191.         [6].d                <-        Julia control point, real (iff julia image requested)
  192.         [7].d                <-        Julia control point, imaginary (iff julia image requested)
  193.  
  194. ---
  195.  
  196.     ConfigureView.  Called when the user presses the "Setup" botton in the
  197.     New View dialog box (and also when the ECM is initially selected from
  198.     the popup menu).  The ECM may pop up a dialog box to allow
  199.     the user to enter configuration information (e.g. equation coefficients,
  200.     network-server name/ID, etc.).  All such data should be stored in a relocatable
  201.     block allocated by the ECM, whose handle is stored in the ECO structure.
  202.     This routine may be called multiple times, to update the configuration.
  203.     
  204.         [0].bool        ->        nonzero if Julia calculation, zero if M calculation
  205.  
  206. ---
  207.  
  208.     SetupView.  Called after the user clicks OK during the creation of a new view.
  209.     This callin is a relict of an older version of MandelZot, and no existing ECMs make
  210.     any use of it (they do the work at ConfigureView or SetupCalcs time instead).
  211.     
  212.     No parameters are passed in at this time.  Returning an error code will cause the
  213.     creation of the new view to be aborted.
  214.     
  215. ---
  216.  
  217.     GetViewInfo.  Called after the view data structure has been initialized, and
  218.     before calculation begins.  ECM must return information about the characteristics
  219.     of the view:  whether the distance-estimator feature is available, whether the
  220.     Mariani-Silver algorithm should be enabled, information concerning the symmetry
  221.     of the resulting image, etc.
  222.  
  223.         [0].e                ->        Minimum real value displayed in window
  224.         [1].e                ->        Maximum real value displayed in window
  225.         [2].e                ->        Minimum imaginary value displayed in window
  226.         [3].e                ->        Maximum imaginary value displayed in window
  227.         [4].si            ->        Dwell limit [0..32765]
  228.         [5].d                ->        Escape radius
  229.         [6].bool        ->        nonzero if Julia calculation, zero if M calculation
  230.         [7].e                ->        Julia control point, real (iff julia image requested)
  231.         [8].e                ->        Julia control point, imaginary (iff julia image requested)
  232.         
  233.         [0].bool         <-        nonzero if distance-estimator capability is available
  234.         [1].bool        <-        nonzero if Mariani/Silver algorithm is suitable
  235.         [2].flags        <-        symmetry characteristics: horizontal, vertical, across-origin,
  236.                                             or an or'ed combination thereof.
  237.         [3].e                <-        real axis of symmetry, if any symmetry is specified
  238.         [4].e                <-        imaginary axis of symmetry, if any symmetry is specified
  239.         [5].si            <-        # of bytes of private context storage required per point during
  240.                           incremental iteration (must be returned only if synchronous-orbit
  241.                           capability was specified in the "does" flags)
  242.         [9].bool        <-        nonzero if the Sherman contour crawling algorithm is safe to use
  243.         [10].bool        <-        nonzero if synchronous-orbit mode (CalcIncremental) is available                                            
  244.  
  245. ---
  246.  
  247.     SetupCalcs.  Called when the view data structure has been initialized, and
  248.     calculation is about to begin.  ECM should set up any data it needs to perform
  249.     the calculation, based on the current calculation parameters.  May be called
  250.     more than once, if the user changes the calculation parameters.
  251.     
  252.         [0].e                ->        Minimum real value displayed in window
  253.         [1].e                ->        Maximum real value displayed in window
  254.         [2].e                ->        Minimum imaginary value displayed in window
  255.         [3].e                ->        Maximum imaginary value displayed in window
  256.         [4].si            ->        Dwell limit [0..32765]
  257.         [5].d                ->        Escape radius
  258.         [6].bool        ->        nonzero if Julia calculation, zero if M calculation
  259.         [7].e                ->        Julia control point, real (iff julia image requested)
  260.         [8].e                ->        Julia control point, imaginary (iff julia image requested)
  261.         [9].bool        ->        nonzero if distance-estimator, zero if point-by-point
  262.         [10].r            ->        Rectangle framing the window
  263.  
  264. ---
  265.  
  266.     CalcsGo.  Called when the program has decided to start calling CalcTimeSlicd.
  267.     ECM should grab any resources needed to do calculation (external hardware,
  268.     network calculation server, etc.).
  269.  
  270.     No parameters at this time;  success is assumed.
  271.  
  272. ---
  273.  
  274.     CalcsStop.  Called when the program has decided to stop calling CalcTimeSlice.
  275.     ECM should release any resources it grabbed at CalcsGo time.
  276.  
  277.     No parameters at this time;  success is assumed.
  278.  
  279. ---
  280.  
  281.     CalcOne.  Called to request calculation of the dwell (and, optionally,
  282.     distance-to-nearest-interior-point) of a single point.
  283.     
  284.         [0].e                ->         Real coordinate of point
  285.         [1].e                ->        Imaginary coordinate of point
  286.         [2].si            ->        Dwell limit
  287.         [3].d                ->        Escape radius
  288.         [4].bool        ->        nonzero if Julia calculation, zero if M calculation
  289.         [5].bool        ->        nonzero if distance-estimator, zero if point-by-point
  290.         [6].e                ->        Julia control point, real (iff julia image requested)
  291.         [7].e                ->        Julia control point, imaginary (iff julia image requested)
  292.         [8].flags        ->        Flag indicating math mode in use
  293.  
  294.         [0].si            <-        Dwell of point [0..limit), or
  295.                                             "on border" == limit, or
  296.                                             "in M"            == 32766 (InTheSet).
  297.         [1].e                <-        Estimated distance to nearest interior point (iff
  298.                                             distance-estimator mode), or -1 == "beats me!"
  299.  
  300. ---
  301.  
  302.     CalcTimeSlice.  Called to give a bulk-calculation-mode ECM an opportunity to
  303.     calculate something.  CalcTimeSlice calls will occur in the middle of a
  304.     CalcGo/CalcStop pair.  ECM should do some calculating, if possible;  stuff
  305.     dwell values into the array;  and use callbacks to instruct the program to
  306.     display points/lines/rectangles of data values on the screen.  ECM can draw to
  307.     the window if desired (it's the current GrafPort).
  308.     
  309.         [0].e                ->        Minimum real value displayed in window
  310.         [1].e                ->        Maximum real value displayed in window
  311.         [2].e                ->        Minimum imaginary value displayed in window
  312.         [3].e                ->        Maximum imaginary value displayed in window
  313.         [4].si            ->        Dwell limit [0..32765]
  314.         [5].d                ->        Escape radius
  315.         [6].bool        ->        nonzero if Julia calculation, zero if M calculation
  316.         [7].e                ->        Julia control point, real (iff julia image requested)
  317.         [8].e                ->        Julia control point, imaginary (iff julia image requested)
  318.         [9].bool        ->        nonzero if distance-estimator, zero if point-by-point
  319.         [10].r            ->        Rectangle framing the window
  320.         [11].r            ->        Rect which frames entire array (if calculation is not currently
  321.                                             constrained) or frames constrained area.  ECM should limit its
  322.                                             calculations and drawing to points within this rectangle.
  323.         [12].h            ->        Handle to array of dwell values, stored in row-major order
  324.         [13].flags    ->        Flag indicating math mode in use
  325.         
  326.         [0].si            <-        SliceOK if all is well and useful work was done;
  327.                                             SliceIdle if all is well but nothing much happened (little time used);
  328.                                             SliceDone if all is well and calculations for the area framed by
  329.                                             the [11].r parameter have been completed;
  330.                                             SliceSuspend if something has gone awry and calculations should
  331.                                             be suspended until the user hits command-G again.
  332.  
  333. ---
  334.  
  335.     InvalInternals.  Called when MandelZot loads a view's private data from a save-
  336.     file, or after an "Extract selection" command.  Call informs ECM that any pointers
  337.     or handles stashed in the view's private data block are no longer valid... they may
  338.     point to the parent window's private data (after an "Extract selection) or to
  339.     memory locations from a former lifetime (after loading a save-file).  ECM should zap
  340.     any pointers or handles (reset them to NULL, or allocate new blocks of the necessary
  341.     sizes and replace the old handles).  ECM should _not_ attempt to access, or dispose of
  342.     blocks referenced by the invalidated handles or pointers... they're off limits!!
  343.         
  344. ---
  345.  
  346.     GetViewString.  Called when the program wants a human-readable interpretation
  347.     of the view's private data.  ECM should convert relevant portions of the
  348.     private data (e.g. polynomial coefficients, exit conditions, etc.) to printable
  349.     form, and return them in the form of a PASCAL string of up to 255 characters.
  350.     
  351.         [0].p                ->        Pointer to an Str255 (PASCAL string) of indeterminate
  352.                                             contents;  program should stuff string into this structure.
  353.  
  354. ---
  355.  
  356.     InitIncrementalState.  Called when the program is about to begin incremental
  357.     iteration on set of points in synchronous-orbit mode.  ECM must initialize the
  358.     block of data identified by the given handle to a state which reflects "iteration
  359.     zero" of a point.  Called only if the ECM specified a non-zero amount of private
  360.     state information.
  361.     
  362.         [0].h                ->        Handle to an unlocked relocateable block which ECM should
  363.                                             initialize to reflect "iteration zero" status.
  364.  
  365. ---
  366.  
  367.     CalcIncremental.  Called during synchronous-orbit operation, to iterate a single
  368.     point one step further along its trajectory.
  369.     
  370.         [0].e                ->         Real coordinate of iterated point
  371.         [1].e                ->        Imaginary coordinate of iterated point
  372.         [2].e                ->         Real coordinate of original (seed) point
  373.         [3].e                ->        Imaginary coordinate of original point
  374.         [4].bool        ->        nonzero if Julia calculation, zero if M calculation
  375.         [5].si            ->        Dwell count prior to iteration
  376.         [6].e                ->        Julia control point, real (iff julia image requested)
  377.         [7].e                ->        Julia control point, imaginary (iff julia image requested)
  378.         [8].flags        ->        Flag indicating math mode in use
  379.         [9].d                ->        Escape radius
  380.         [10].ptr        ->        Pointer to point's private state information
  381.  
  382.         [0].e                <-         Real coordinate of iterated point (updated)
  383.         [1].e                <-        Imaginary coordinate of iterated point (updated)
  384.         [2].bool        <-        Nonzero if point escaped, zero otherwise
  385.         [3].si            <-        Dwell to color this point, if it escaped ([2].bool nonzero);
  386.                                             irrelevant if point did not escape.
  387.  
  388. */
  389.  
  390. /*
  391.         Function codes which the ECM can use when calling back to the main program
  392. */
  393.  
  394. enum CallbackFunction
  395.     {
  396.         DisplayPoint                    = 100,
  397.         DisplayRowSeg                    = 101,
  398.         DisplayRect                        = 102,
  399.         SetPenColor                        = 103,
  400.         SetStatusString                = 104
  401.     };
  402.  
  403. /*
  404.         Parameter definitions for the various callbacks
  405.         
  406.         "->" represents a value passed by the ECM to the program's callback routine
  407.         "<-" represents a value filled in by the callback prior to returning.
  408.         
  409.         DisplayPoint.  Used to ask the program to display a specified dwell-point in the
  410.         window.  ECM must stuff the dwell value into the dwell array before making this
  411.         call.
  412.         
  413.         [0].si            ->        X coordinate of point to be displayed
  414.         [1].si            ->        Y coordinate of point to be displayed
  415.  
  416. ---
  417.  
  418.         DisplayRowSeg.  Used to ask the program to display one or more dwell
  419.         points in a specified row.  ECM must stuff the values into the dwell array before
  420.         making this call.
  421.         
  422.         [0].si            ->        X coordinate at left end of row segment.
  423.         [1].si            ->        X coordinate at right end of row segment.
  424.         [2].si            ->        Y coordinate of row.
  425.  
  426. ---
  427.  
  428.         DisplayRect.  Used to ask the program to display a rectangular portion of the
  429.         view window, using the current dwell values for those points.
  430.         
  431.         [0].r                ->        Rect specifying the area to be displayed.
  432.         
  433.         n.b. the display occurs when the call is made.  Another way to do this is to
  434.         simply InvalRect(&rect);  the program will erase and redraw the specified
  435.         rectangle the next time around the event loop.
  436.  
  437. ---
  438.  
  439.         SetPenColor.  Used to ask the program to set the port's pen to the proper
  440.         color for drawing points of a specific dwell.
  441.         
  442.         [0].r                ->        Dwell value for which pen color should be set.
  443.         
  444.         n.b. ECM should reset the pen to black before returning.
  445.  
  446. ---
  447.  
  448.         SetStatusString.  Used to ask the program to update the status advisory
  449.         displayed (sometimes) in the horizontal scroll bar area.
  450.         
  451.         [0].p                ->        Pointer to Pascal Str255 string to be displayed.
  452.         
  453.         n.b. the specified string may or may not actually be displayed, at this
  454.         time or later.  This feature should be used for "FYI" information only;
  455.         it's not suitable for use in developing any sort of real user interface.
  456.  
  457. */
  458.  
  459.